HAL I2S Functions

IRQ handler/callbacks/register callbacks functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group6

This subsection provides functions to process I2S interrupts and register I2S process and error callbacks:

• The function HAL_I2S_IRQHandler() to handle all I2S interrupts

There are two ways to use callbacks: Override weak callbacks functions:

• Call the function HAL_I2S_ErrorCallback() to indicate invalid operation is completed

• Call the function HAL_I2S_TxCpltCallback() to indicate Tx transfer is completed

• Call the function HAL_I2S_TxHalfCpltCallback() to indicate Tx half transfer is completed

• Call the function HAL_I2S_RxCpltCallback() to indicate Rx transfer is completed

• Call the function HAL_I2S_RxHalfCpltCallback() to indicate Rx half transfer is completed

• Call the function HAL_I2S_TxRxCpltCallback() to indicate Tx/Rx transfer is completed

• Call the function HAL_I2S_TxRxHalfCpltCallback() to indicate Tx/Rx half transfer is completed

• Call the function HAL_I2S_AbortCpltCallback() to indicate Abort operation is completed

Register callbacks:

• Call the function HAL_I2S_RegisterErrorCallback() to register the Error callback

• Call the function HAL_I2S_RegisterTxCpltCallback() to register the Tx transfer complete callback

• Call the function HAL_I2S_RegisterTxHalfCpltCallback() to register the Tx half transfer complete callback

• Call the function HAL_I2S_RegisterRxCpltCallback() to register the Rx transfer complete callback

• Call the function HAL_I2S_RegisterRxHalfCpltCallback() to register the Rx half transfer complete callback

• Call the function HAL_I2S_RegisterTxRxCpltCallback() to register the Tx/Rx transfer complete callback

• Call the function HAL_I2S_RegisterTxRxHalfCpltCallback() to register the Tx/Rx half transfer complete callback

• Call the function HAL_I2S_RegisterAbortCpltCallback() to register the Abort operation complete callback

Depending on the process function in use, different callbacks can be triggered:

Process API \ Callbacks	HAL_I2S_Transmit_IT	HAL_I2S_Receive_IT	HAL_I2S_TransmitReceive_IT
HAL_I2S_TxCpltCallback	x
HAL_I2S_RxCpltCallback		x
HAL_I2S_TxRxCpltCallback			x
HAL_I2S_ErrorCallback	x	x	x

Process API \ Callbacks	HAL_I2S_Transmit_DMA	HAL_I2S_Receive_DMA	HAL_I2S_TransmitReceive_DMA
HAL_I2S_TxHalfCpltCallback*	x
HAL_I2S_TxCpltCallback	x
HAL_I2S_RxHalfCpltCallback*		x
HAL_I2S_RxCpltCallback		x
HAL_I2S_TxRxHalfCpltCallback*			x
HAL_I2S_TxRxCpltCallback			x
HAL_I2S_ErrorCallback**	x	x	x

Process API \ Callbacks	HAL_I2S_Abort_IT
HAL_I2S_AbortCpltCallback	x
HAL_I2S_ErrorCallback	x

Note

* these callbacks might be called following DMA IRQ management, not I2Sx IRQ management.

Note

** these callbacks might be called following DMA IRQ management, or I2Sx IRQ management.

Functions

void HAL_I2S_IRQHandler ( hal_i2s_handle_t * hi2s )

Handle I2S interrupt request.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_ErrorCallback ( hal_i2s_handle_t * hi2s )

I2S Error callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_TxCpltCallback ( hal_i2s_handle_t * hi2s )

Tx transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_RxCpltCallback ( hal_i2s_handle_t * hi2s )

Rx transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_TxRxCpltCallback ( hal_i2s_handle_t * hi2s )

Tx and Rx transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_TxHalfCpltCallback ( hal_i2s_handle_t * hi2s )

Tx half transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_RxHalfCpltCallback ( hal_i2s_handle_t * hi2s )

Rx half transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_TxRxHalfCpltCallback ( hal_i2s_handle_t * hi2s )

Tx and Rx half transfer complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

void HAL_I2S_AbortCpltCallback ( hal_i2s_handle_t * hi2s )

Abort complete callback.

Warning

Do not modify this weak function. Implement the callback in the user file when needed.

Parameters :

hi2s – Pointer to hal_i2s_handle_t.

hal_status_t HAL_I2S_RegisterErrorCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Error callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Error callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterTxCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Tx complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Tx complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterRxCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Rx complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Rx complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterTxRxCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Tx/Rx complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Tx/Rx complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterTxHalfCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Tx half complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Tx half complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterRxHalfCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Rx half complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Rx half complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterTxRxHalfCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Tx/Rx half complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Tx/Rx half complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

hal_status_t HAL_I2S_RegisterAbortCpltCallback ( hal_i2s_handle_t * hi2s , hal_i2s_cb_t p_callback )

Register the Abort complete callback.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_callback – Pointer to the Abort complete callback function.

Return values :

• HAL_INVALID_PARAM – Invalid Callback pointer.

• HAL_OK – Register completed successfully.

Peripheral current frequency, state and errors functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group7

This subsection provides functions to read peripheral current frequency, current state and last occurred errors.

• HAL_I2S_GetClockFreq() function to retrieve the current clock frequency of the I2S peripheral.

• HAL_I2S_GetState() function to retrieve the current state of the I2S peripheral.

• HAL_I2S_GetLastErrorCodes() function to retrieve the error codes in case of HAL_ERROR return available under the compilation switch USE_HAL_I2S_GET_LAST_ERRORS.

Functions

uint32_t HAL_I2S_GetClockFreq ( const hal_i2s_handle_t * hi2s )

Return the peripheral clock frequency for I2S.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• uint32_t – Frequency in Hz.

• 0 – Source clock of the hi2s not configured or not ready.

hal_i2s_state_t HAL_I2S_GetState ( const hal_i2s_handle_t * hi2s )

Retrieve the I2S handle state.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

hal_i2s_state_t I2S state.

uint32_t HAL_I2S_GetLastErrorCodes ( const hal_i2s_handle_t * hi2s )

Retrieve the I2S errors codes.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

uint32_t – Returned value can be a combination of the following values:

• HAL_I2S_ERROR_NONE

• HAL_I2S_ERROR_OVR

• HAL_I2S_ERROR_UDR

• HAL_I2S_ERROR_DMA

• HAL_I2S_ERROR_FRE

• HAL_I2S_ERROR_IO_LOCKED

Acquire/release Bus functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group8

This subsection provides functions to acquire/release the bus based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

• Call HAL_I2S_AcquireBus() from thread mode only (not from handler mode, i.e., from ISR).

• Call HAL_I2S_ReleaseBus() from thread mode or from handler mode, i.e., from ISR.

Functions

hal_status_t HAL_I2S_AcquireBus ( hal_i2s_handle_t * hi2s , uint32_t timeout_ms )

Acquire the I2S bus using the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

Call HAL_I2S_AcquireBus from thread mode only (not from handler mode, i.e., from ISR).

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• timeout_ms – Time to wait before the bus is occupied by the handle.

Return values :

• HAL_OK – Operation started successfully.

• HAL_ERROR – Operation completed with error.

hal_status_t HAL_I2S_ReleaseBus ( hal_i2s_handle_t * hi2s )

Release the I2S bus thanks to the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_I2S_ReleaseBus function can be called from thread mode or from handler mode i.e from ISR.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation started successfully.

• HAL_ERROR – Operation completed with error.

Set/Get user data

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group9

A set of functions to manage a user data pointer stored in the I2S handle:

• HAL_I2S_SetUserData() Set the user data in the handle

• HAL_I2S_GetUserData() Get the user data from the handle

Functions

void HAL_I2S_SetUserData ( hal_i2s_handle_t * hi2s , const void * p_user_data )

Store the user data pointer in the handle.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_user_data – Pointer to the user data.

const void * HAL_I2S_GetUserData ( const hal_i2s_handle_t * hi2s )

Retrieve the user data pointer from the handle.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

Pointer – to the user data.

Initialization and de-initialization functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group1

This subsection provides functions to initialize and deinitialize the I2Sx peripheral:

• Call the function HAL_I2S_Init() to initialize the selected I2S handle and associate an instance.

• Call the function HAL_I2S_DeInit() to restore the default initialization of the selected I2Sx peripheral.

Functions

hal_status_t HAL_I2S_Init ( hal_i2s_handle_t * hi2s , hal_i2s_t instance )

Initialize the I2S according to the associated handle.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• instance – I2S instance.

Return values :

• HAL_INVALID_PARAM – When the handle is NULL.

• HAL_ERROR – When the MUTEX cannot be created.

• HAL_OK – HAL I2S driver correctly initialized for the given I2S instance.

void HAL_I2S_DeInit ( hal_i2s_handle_t * hi2s )

Deinitialize the I2S driver for the given handle.

Parameters :

hi2s – pointer to a hal_i2s_handle_t.

Configuration functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group2

This subsection provides functions to configure the I2Sx peripheral:

• Call the function HAL_I2S_MASTER_SetConfig() to configure the selected device in master mode with the selected configuration:

  • Mode

  • Standard

  • Data format

  • Audio frequency selected

  • Clock polarity

  • Bit order

• Call the function HAL_I2S_MASTER_GetConfig() to retrieve the current global configuration set by the application in master mode.

• Call the function HAL_I2S_SLAVE_SetConfig() to configure the selected device in slave mode with the selected configuration:

  • Mode

  • Standard

  • Data format

  • Clock polarity

  • Bit order

• Call the function HAL_I2S_SLAVE_GetConfig() to retrieve the current global configuration set by the application in slave mode.

Functions

hal_status_t HAL_I2S_MASTER_SetConfig ( hal_i2s_handle_t * hi2s , const hal_i2s_master_config_t * p_config )

Set the configuration to the I2S peripheral in Master mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_config – Pointer to hal_i2s_master_config_t configuration structure.

Return values :

• HAL_INVALID_PARAM – Invalid parameters.

• HAL_ERROR – When IO locked.

• HAL_OK – I2S instance has been correctly configured.

hal_status_t HAL_I2S_SLAVE_SetConfig ( hal_i2s_handle_t * hi2s , const hal_i2s_slave_config_t * p_config )

Set the configuration to the I2S peripheral in Slave mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_config – Pointer to hal_i2s_slave_config_t configuration structure.

Return values :

• HAL_INVALID_PARAM – Invalid parameters.

• HAL_ERROR – When IO locked.

• HAL_OK – I2S instance has been correctly configured.

void HAL_I2S_MASTER_GetConfig ( const hal_i2s_handle_t * hi2s , hal_i2s_master_config_t * p_config )

Retrieve the configuration of the I2S peripheral in Master mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_config – Pointer to hal_i2s_master_config_t configuration structure.

void HAL_I2S_SLAVE_GetConfig ( const hal_i2s_handle_t * hi2s , hal_i2s_slave_config_t * p_config )

Retrieve the configuration of the I2S peripheral in Slave mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_config – Pointer to hal_i2s_slave_config_t configuration structure.

Features functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group3

This subsection provides functions to configure additional features for the selected I2Sx peripheral.

• Master Clock Output configuration:

  • HAL_I2S_MASTER_EnableClockOutput()

  • HAL_I2S_MASTER_DisableClockOutput()

  • HAL_I2S_MASTER_IsEnabledClockOutput()

• Word Select Inversion configuration:

  • HAL_I2S_EnableWSInversion()

  • HAL_I2S_DisableWSInversion()

  • HAL_I2S_IsEnabledWSInversion()

• Master Keep IO State configuration:

  • HAL_I2S_MASTER_EnableKeepIOState()

  • HAL_I2S_MASTER_DisableKeepIOState()

  • HAL_I2S_MASTER_IsEnabledKeepIOState()

• IO Swap configuration:

  • HAL_I2S_EnableIOSwap()

  • HAL_I2S_DisableIOSwap()

  • HAL_I2S_IsEnabledIOSwap()

• Channel Length Detection Error configuration:

  • HAL_I2S_SLAVE_EnableLengthDetectionError()

  • HAL_I2S_SLAVE_DisableLengthDetectionError()

  • HAL_I2S_SLAVE_IsEnabledLengthDetectionError()

• IO lock configuration:

  • HAL_I2S_LockIOConfig()

  • HAL_I2S_IsLockedIOConfig()

• FIFO Threshold configuration:

  • HAL_I2S_SetFifoThreshold()

  • HAL_I2S_GetFifoThreshold()

• Data alignment for 24-bit data format configuration:

  • HAL_I2S_SetData24BitsAlignedRight()

  • HAL_I2S_SetData24BitsAlignedLeft()

Functions

hal_status_t HAL_I2S_MASTER_EnableClockOutput ( hal_i2s_handle_t * hi2s )

Enable I2S Master Clock Output.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_I2S_MASTER_DisableClockOutput ( hal_i2s_handle_t * hi2s )

Disable I2S Master Clock Output.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_master_clk_output_status_t HAL_I2S_MASTER_IsEnabledClockOutput ( const hal_i2s_handle_t * hi2s )

Get I2S Master Clock Output status.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Master clock output status.

hal_status_t HAL_I2S_EnableWSInversion ( const hal_i2s_handle_t * hi2s )

Enable I2S Word Select Inversion.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_I2S_DisableWSInversion ( const hal_i2s_handle_t * hi2s )

Disable I2S Word Select Inversion.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_ws_inversion_status_t HAL_I2S_IsEnabledWSInversion ( const hal_i2s_handle_t * hi2s )

Check I2S Word Select Inversion status.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Word select inversion status.

hal_status_t HAL_I2S_MASTER_EnableKeepIOState ( hal_i2s_handle_t * hi2s )

Enable Master Keep IO State feature. The peripheral always keeps control of all associated GPIOs to prevent any glitches on the line.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – When IO is locked.

hal_status_t HAL_I2S_MASTER_DisableKeepIOState ( hal_i2s_handle_t * hi2s )

Disable Master Keep IO State feature.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – When IO is locked.

hal_i2s_master_keep_io_state_status_t HAL_I2S_MASTER_IsEnabledKeepIOState ( const hal_i2s_handle_t * hi2s )

Check I2S Master Keep IO State feature status.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Master keep IO state status.

hal_status_t HAL_I2S_EnableIOSwap ( hal_i2s_handle_t * hi2s )

Enable IO Swap.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – When IO is locked.

hal_status_t HAL_I2S_DisableIOSwap ( hal_i2s_handle_t * hi2s )

Disable IO Swap.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – When IO is locked.

hal_i2s_io_swap_status_t HAL_I2S_IsEnabledIOSwap ( const hal_i2s_handle_t * hi2s )

Check I2S IO swap status.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

IO swap status.

hal_status_t HAL_I2S_SLAVE_EnableLengthDetectionError ( const hal_i2s_handle_t * hi2s )

Enable Channel Length detection error only in slave mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_I2S_SLAVE_DisableLengthDetectionError ( const hal_i2s_handle_t * hi2s )

Disable Channel Length detection error only in slave mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_slave_length_detection_error_status_t HAL_I2S_SLAVE_IsEnabledLengthDetectionError ( const hal_i2s_handle_t * hi2s )

Check I2S Channel Length detection error status only in slave mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Slave channel detection error status.

hal_status_t HAL_I2S_LockIOConfig ( const hal_i2s_handle_t * hi2s )

Lock the IO configuration.

Note

The reset of the IOLock bit is done by hardware.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_io_cfg_status_t HAL_I2S_IsLockedIOConfig ( const hal_i2s_handle_t * hi2s )

Retrieve the IO configuration status.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

hal_i2s_io_cfg_status_t. –

hal_status_t HAL_I2S_SetFifoThreshold ( const hal_i2s_handle_t * hi2s , const hal_i2s_fifo_threshold_t fifo_threshold )

Set the FIFO threshold level.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• fifo_threshold – This parameter must be a value of hal_i2s_fifo_threshold_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_fifo_threshold_t HAL_I2S_GetFifoThreshold ( const hal_i2s_handle_t * hi2s )

Retrieve the bit order for data transfers (MSB or LSB bit first).

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S FIFO threshold level configuration.

hal_status_t HAL_I2S_SetData24BitsAlignedRight ( const hal_i2s_handle_t * hi2s )

Set the data alignment to right.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

hal_status_t HAL_I2S_SetData24BitsAlignedLeft ( const hal_i2s_handle_t * hi2s )

Set the data alignment to left.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

HAL_OK – Operation completed successfully.

Items functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group4

This subsection provides functions to change and retrieve a single configuration in the IDLE state.

• HAL_I2S_SetMode(): Set the mode of the I2S peripheral.

• HAL_I2S_GetMode(): Retrieve the mode of the I2S peripheral.

• HAL_I2S_SetStandard(): Set the standard of the I2S peripheral.

• HAL_I2S_GetStandard(): Retrieve the standard of the I2S peripheral.

• HAL_I2S_SetDataFormat(): Set the data format of the I2S peripheral.

• HAL_I2S_GetDataFormat(): Retrieve the data format of the I2S peripheral.

• HAL_I2S_MASTER_SetAudioFrequency(): Set the master Word Select audio frequency of the I2S peripheral.

• HAL_I2S_MASTER_GetAudioFrequency(): Retrieve the master Word Select audio frequency of the I2S peripheral.

• HAL_I2S_SetClockPolarity(): Set the clock polarity of the I2S peripheral.

• HAL_I2S_GetClockPolarity(): Retrieve the clock polarity of the I2S peripheral.

• HAL_I2S_SetBitOrder(): Set the bit order for data transfers (MSB or LSB bit first) of the I2S peripheral.

• HAL_I2S_GetBitOrder(): Retrieve the bit order for data transfers (MSB or LSB bit first) of the I2S peripheral.

• HAL_I2S_SetTxDMA(): Link the transmit DMA handle to the I2S handle.

• HAL_I2S_SetRxDMA(): Link the receive DMA handle to the I2S handle.

Functions

hal_status_t HAL_I2S_SetMode ( const hal_i2s_handle_t * hi2s , const hal_i2s_mode_t mode )

Set the transfer mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• mode – This parameter must be a value of hal_i2s_mode_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_mode_t HAL_I2S_GetMode ( const hal_i2s_handle_t * hi2s )

Retrieve the transfer mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S mode configuration.

hal_status_t HAL_I2S_SetStandard ( const hal_i2s_handle_t * hi2s , const hal_i2s_standard_t standard )

Set the standard.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• standard – This parameter must be a value of hal_i2s_standard_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_standard_t HAL_I2S_GetStandard ( const hal_i2s_handle_t * hi2s )

Retrieve the standard.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S standard configuration.

hal_status_t HAL_I2S_SetDataFormat ( const hal_i2s_handle_t * hi2s , const hal_i2s_data_format_t format )

Set the data format.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• format – This parameter must be a value of hal_i2s_data_format_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_data_format_t HAL_I2S_GetDataFormat ( const hal_i2s_handle_t * hi2s )

Retrieve the data format.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S data format configuration.

hal_status_t HAL_I2S_MASTER_SetAudioFrequency ( hal_i2s_handle_t * hi2s , const hal_i2s_master_audio_frequency_t frequency_ws_hz )

Set the master Word Select audio frequency.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• frequency_ws_hz – This parameter must be a value of hal_i2s_master_audio_frequency_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_master_audio_frequency_t HAL_I2S_MASTER_GetAudioFrequency ( const hal_i2s_handle_t * hi2s )

Retrieve the master Word Select audio frequency.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S closest audio frequency configuration to the real audio frequency.

hal_status_t HAL_I2S_SetClockPolarity ( const hal_i2s_handle_t * hi2s , const hal_i2s_clock_polarity_t clock_polarity )

Set the clock polarity.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• clock_polarity – This parameter must be a value of hal_i2s_clock_polarity_t.

Return values :

HAL_OK – Operation completed successfully.

hal_i2s_clock_polarity_t HAL_I2S_GetClockPolarity ( const hal_i2s_handle_t * hi2s )

Retrieve the clock polarity.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S clock polarity configuration.

hal_status_t HAL_I2S_SetBitOrder ( hal_i2s_handle_t * hi2s , const hal_i2s_bit_order_t bit_order )

Set the bit order for data transfers (MSB or LSB bit first).

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• bit_order – This parameter must be a value of hal_i2s_bit_order_t.

Return values :

• HAL_ERROR – When IO is locked.

• HAL_OK – Operation completed successfully.

hal_i2s_bit_order_t HAL_I2S_GetBitOrder ( const hal_i2s_handle_t * hi2s )

Retrieve the bit order for data transfers (MSB or LSB bit first).

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Returns :

Current I2S bit order configuration.

hal_status_t HAL_I2S_SetTxDMA ( hal_i2s_handle_t * hi2s , hal_dma_handle_t * hdma )

Link the Transmit DMA handle to the I2S handle.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t structure.

• hdma – Pointer to a hal_dma_handle_t structure.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_INVALID_PARAM – Invalid parameter.

hal_status_t HAL_I2S_SetRxDMA ( hal_i2s_handle_t * hi2s , hal_dma_handle_t * hdma )

Link the Receive DMA handle to the I2S handle.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• hdma – Pointer to a hal_dma_handle_t structure.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_INVALID_PARAM – Invalid parameter.

IO operation functions

STM32C562xx STM32C5A3xx STM32C542xx

group I2S_Exported_Functions_Group5

This subsection provides a set of functions allowing the management of the I2S data transfers.

The I2S supports both master and slave mode: There are two modes of transfer:

• Blocking mode: The communication is performed in polling mode. The status of all data processing is returned by the same function after finishing the transfer.

• No-Blocking mode: The communication is performed using Interrupts or DMA. These functions return the status of the transfer startup. The end of the data processing will be indicated through the dedicated I2S IRQ when using Interrupt mode or the DMA IRQ when using DMA mode.

Functions

uint32_t HAL_I2S_MASTER_GetRealAudioFrequency ( const hal_i2s_handle_t * hi2s )

Return the real master Word Select audio frequency.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• 0 – I2S source clock frequency not active

• Other – value, Real audio frequency in Hz.

hal_status_t HAL_I2S_Transmit ( hal_i2s_handle_t * hi2s , const void * p_data , uint32_t size_sample , uint32_t timeout_ms )

Transmit an amount of data in blocking mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to send in bytes.

• timeout_ms – Timeout duration.

Returns :

hal_status_t.

hal_status_t HAL_I2S_Receive ( hal_i2s_handle_t * hi2s , void * p_data , uint32_t size_sample , uint32_t timeout_ms )

Receive an amount of data in blocking mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to receive. Transfer size must be a multiplier of the fifo threshold.

• timeout_ms – Timeout duration.

Returns :

hal_status_t.

hal_status_t HAL_I2S_TransmitReceive ( hal_i2s_handle_t * hi2s , const void * p_tx_data , void * p_rx_data , uint32_t size_sample , uint32_t timeout_ms )

Transmit and Receive an amount of data in blocking mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_tx_data – Pointer to data buffer to transmit.

• p_rx_data – Pointer to data buffer to receive.

• size_sample – Amount of data to send and receive.

• timeout_ms – Timeout duration.

Returns :

hal_status_t.

hal_status_t HAL_I2S_Transmit_IT ( hal_i2s_handle_t * hi2s , const void * p_data , uint32_t size_sample )

Transmit an amount of data in Interrupt mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to send.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_Receive_IT ( hal_i2s_handle_t * hi2s , void * p_data , uint32_t size_sample )

Receive an amount of data in Interrupt mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to receive.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_TransmitReceive_IT ( hal_i2s_handle_t * hi2s , const void * p_tx_data , void * p_rx_data , uint32_t size_sample )

Transmit and Receive an amount of data in Interrupt mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_tx_data – Pointer to data buffer to transmit.

• p_rx_data – Pointer to data buffer to receive.

• size_sample – Amount of data to send and receive.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_Transmit_DMA ( hal_i2s_handle_t * hi2s , const void * p_data , uint32_t size_sample )

Transmit an amount of data in DMA mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to send.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_ERROR – Operation completed with error.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_Receive_DMA ( hal_i2s_handle_t * hi2s , void * p_data , uint32_t size_sample )

Receive an amount of data in DMA mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_data – Pointer to data buffer.

• size_sample – Amount of data to receive.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_ERROR – Operation completed with error.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_TransmitReceive_DMA ( hal_i2s_handle_t * hi2s , const void * p_tx_data , void * p_rx_data , uint32_t size_sample )

Transmit and Receive an amount of data in DMA mode.

Parameters :

• hi2s – Pointer to a hal_i2s_handle_t.

• p_tx_data – Pointer to data buffer to transmit.

• p_rx_data – Pointer to data buffer to receive.

• size_sample – Amount of data to send and receive.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_BUSY – Concurrent process ongoing.

• HAL_ERROR – Operation completed with error.

• HAL_INVALID_PARAM – Invalid parameters.

hal_status_t HAL_I2S_MASTER_Pause ( hal_i2s_handle_t * hi2s )

Pause the process in master mode.

Note

During the process of pause and resume, some data will be missed.

Note

To prevent any glitches on data line, the function HAL_I2S_MASTER_EnableKeepIOState must be used.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – No process ongoing.

hal_status_t HAL_I2S_MASTER_Resume ( hal_i2s_handle_t * hi2s )

Resume the process in master mode.

Note

During the process of pause and resume, some data will be missed.

Note

To prevent any glitches on data line, the function HAL_I2S_MASTER_EnableKeepIOState must be used.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – No process paused.

hal_status_t HAL_I2S_Abort ( hal_i2s_handle_t * hi2s )

Abort ongoing transfer in blocking mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – Operation completed with error.

hal_status_t HAL_I2S_Abort_IT ( hal_i2s_handle_t * hi2s )

Abort ongoing transfer in no-blocking mode.

Parameters :

hi2s – Pointer to a hal_i2s_handle_t.

Return values :

• HAL_OK – Operation completed successfully.

• HAL_ERROR – Operation completed with error.